Inside Macintosh: QuickDraw GX Objects /

Chapter 8 - Tag Objects / Tag Objects Reference

Functions / Directly Manipulating the Data in a Tag Object

GXGetTagStructure

You can use the GXGetTagStructure function to get a pointer to the contents of a tag object.

void *GXGetTagStructure(gxTag source, long *length);

source

A reference to the tag object whose contents you need access to.

length

A pointer to a value. On return, contains the size in bytes of the contents of the tag object referenced in the source parameter.

function result

A pointer to the contents of the source tag object.

DESCRIPTION

The GXGetTagStructure function returns a pointer to the contents of the tag object referenced in the source parameter. To directly edit a tag's contents, you must first call GXLockTag. You can then call GXGetTagStructure and edit the tag's contents. After editing, you must call GXUnlockTag.

The GXGetTagStructure function is different from the GXGetTag function in that it gives you direct access to the contents of a tag object in QuickDraw GX memory. The GXGetTag function returns a copy of the tag object's contents in a buffer that you have allocated in application memory.

To edit the contents of a tag object, you need to know its format and organization. GXGetTagStructure returns a pointer and a size only; it does not provide you with any information about the internal structure of the tag's contents.

This function does not provide access to tag type information.

SPECIAL CONSIDERATIONS

Note that using the GXGetTagStructure is different from calling GXSetTag, in that it does not allow you to change the size of the tag object.

This function is available for your convenience, in that you do not have to make a copy of the tag object's data, but is rarely needed. In most cases you can use the GXGetTag and GXSetTag functions to manipulate tag contents.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
tag_is_nil
Notices (debugging version)
lockTag_called_as_side_effect

SEE ALSO

The GXLockTag function is described on page 8-21. The GXUnlockTag function is described in the previous section.

The GXGetTag function is described on page 8-18. The GXSetTag function is described on page 8-19.